Get started with the Distance Matrix API

  • This page provides a sample request and response for the Distance Matrix API, demonstrating how to calculate the distance and travel time between two locations.

  • The example uses Washington, DC and New York City, NY as locations and showcases the request URL, cURL command, and expected JSON/XML responses.

  • Users are encouraged to try the example with their own API key and explore further documentation on building requests and understanding responses.

Sample request and response

This example requests the distance matrix data between Washington, DC and New York City, NY, in JSON format:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=New%20York%20City%2C%20NY
  &origins=Washington%2C%20DC
  &units=imperial
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Washington%2C%20DC&destinations=New%20York%20City%2C%20NY&units=imperial&key=YOUR_API_KEY'

Try it! Test this request by entering the URL into your web browser - be sure to replace YOUR_API_KEY with your actual API key. The response shows the distance and duration between the specified origins and destinations.

Learn how to build request URLs, including all available parameters.

This code sample is in JSON and XML formats:

JSON

{
  "destination_addresses": ["New York, NY, USA"],
  "origin_addresses": ["Washington, DC, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "228 mi", "value": 367654 },
              "duration": { "text": "3 hours 55 mins", "value": 14078 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML


 OK
 Washington, DC, USA
 New York, NY, USA
 
  
   OK
   
    14078
    3 hours 55 mins
   
   
    367654
    228 mi

Check the developer's guide to understand the response.